Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/STUTTGART/EDITORS/ZAP130/!Zap/3rdParty/ZapPrimer/ZapPrimer

Text File | 1994-10-15 | 28KB | 585 lines

               o----------------------------------------o
               |                                        |
               |  A short primer for the new Zap user   |
               |                                        |
               |              Version 1.20              |
               |                                        |
               o----------------------------------------o




    Introduction
    ============
This is not a 'manual' for Zap. It is intended as a short instruction
file for users who do not have experience of programmer's editors and
who find the rather technical instructions supplied with Zap confusing.
It will not teach you all about Zap, it won't even mention most of the
more advanced features. The aim is to get the inexperienced user over
the first hurdle so that you can begin to use Zap at the most basic
level. Once you have started to use it in preference to Edit you will
then be able to go on to discover how to change it to make it operate
the way you want. You will also be able to explore some of its more
sophisticated editing functions for yourself.

I assume that you are already familiar with Edit and will describe how
you can set up Zap to work in a similar way.

If you want to print this file (and if you need it I suggest you do)
then the easiest way to do so is to load it into Zap and just press the
Print key.  Alternatively you can double-click on the !Print file in
this same directory which will simply copy the file to your printer.

If you are an experienced computer user who is familiar with editors on
the Archimedes and other computers then don't bother to read this, it
isn't intended for you.



    Copyright
    =========
This text and the files associated with it are (C) David Holden 1993.
They may be freely copied and distributed by any PRIVATE INDIVIDUAL. You
must ONLY copy the complete package including the example Keys, Keystrip
and !Config file. You must NOT distribute it separate from the complete
Zap package to which it applies (currently version 1.20). You must NOT
substitute the Keys file for the one in the Zap application or put the
!Config file into the !Zap application directory. They must be
distributed separately to ensure that the original default files are
always included with Zap.

It may NOT be distributed by any PD or Shareware Library or BBS or any
other not-private media without permission. It may not be changed,
edited, or in any way altered but you may include additional material if
you wish. If you do want to distribute this with Zap please let me know
so that I can supply you with an updates as new versions of Zap appear.

These restrictions have not been imposed because I wish to stop it being
distributed by other libraries. On the contrary I want it to have a wide
circulation so that as many people as possible can be introduced to Zap.
However Zap is constantly being updated and improved and anything I
write or any examples I provide may not apply to other versions.

It is therefore VERY important that these files should only be
distributed as part of the package to which they particularly refer. If
you are running a Library or BBS then write to me at the address below
(send a disc with a copy of your catalogue please) and I will send you
the latest versions of this file and the latest version of Zap. If you
have been sent a copy by either myself or Dominic Symes or if you have
acquired it as part of the COMPLETE !Zap package from any 'authorised'
distributor then  you automatically have permission to distribute it but
ONLY with the version of Zap with which it was included.



                David Holden
                Archimedes Public Domain Library
                39 Knighton Park Road
                Sydenham
                London SE26 5RN


                        _______
                   ____|__     |               (R)
                --|       |    |-------------------
                  |   ____|__  |  Association of
                  |  |       |_|  Shareware
                  |__|   o   |    Professionals
                -----|   |   |---------------------
                     |___|___|    MEMBER




    Text Editors
    ============
There are two types of programs used for writing text on a computer,
Wordprocessors and Text Editors. It might seem that they perform similar
functions but in fact that is not the case. A wordprocessor is used for
producing text which will eventually be turned into a printed document.
This could be anything from a single page letter up to a book. More
exotic wordprocessors can handle fancy fonts and graphics and when they
reach this degree of sophistication they are called Desktop Publishing
programs. Wordprocessor files are not intended to be 'transportable'.
They contain embedded control codes and formatting commands which are
unintelligible to other programs.

Text Editors can be used to prepare text which will be printed but that
is not their main purpose. The files they produce will normally contain
only the 'standard' characters. These are called Plain Text or ASCII
files. In fact different types of computer have different ideas of
'plain text' since the character set will vary between countries. The
character which marks the end of a line is also not standard.

The Archimedes uses the ascii character code 10 at the end of each line,
the BBC computer used code 13 and the PC and Apple Mac use both
together. However in general a plain text file written on one computer
can be read on most other computers once these minor differences have
been put right. This is made easier if you confine yourself to the main
characters which appear on the computer keyboard and avoid special
symbols such as accented and currency characters.

Most text editors have a few simple aids to text formatting such as
variable line length and wordwrap. You will probably be familiar with
these from Edit.

Another use of text editors is for writing Source Code for compilers and
assemblers. Because programmers have special requirements a particular
type of text editor known as a Programmer's Editor has appeared.


    Programmer's Editors
    ====================
The biggest difference between a programmer's editor and a 'simple' text
editor like Edit is that it is, as its name suggest, designed to be used
by programmers. It therefore needs to be able to create and edit source
code for compilers such as 'C' or Pascal. As Basic is such a powerful
and widely used language on the Archimedes ideally it should also be
able to edit Basic programs. The RiscOS 3 version of Edit can do this
although earlier versions could not. It will need powerful Search and
Replace functions and should not be upset by files containing Control
Characters. It will not need complex text formatting or printing
controls because program source code would normally only be printed out
as a 'listing' for the programmer to examine so nothing fancy is needed.
It must be capable of basic text formatting and wordwrap because the
programmer will probably want to use his favourite editor for writing
short 'help' files for his program. Above all is must be FAST.


There is one requirement which separates the 'professional' programmers
editor from simple ones like Edit. Programmers are, by nature, perverse,
individualistic and self opinionated. Wherever three programmers are
gathered together there will be a minimum of four strongly held opinions
on any subject connected with computers. It follows that an editor
designed to be used by such people must be capable of being customised
to suit his/her requirements and temperament. All good programmer's
editors have some means whereby the keys used for the various functions
can be set by the user. They also permit things like screen colours and
as many other factors as possible to be altered.

This is one reason why many new users of Zap become confused and give up
before they realise how superior to Edit it is. The Author of Zap spends
much of his time with computers running UNIX. He has therefore designed
the standard keyboard layout to conform to the UNIX editors with which
he is most familiar. You do not need to be bothered by this. Remember
that almost everything about Zap can be set the way you want it.


    The vanishing cursor
    ====================
Zap has a 'proper' cursor instead of the (often almost invisible) caret
and this is much easier to find, especially as you can define its colour
and make it flash if you wish. Earlier versions of Zap had a 'feature'
(translation:- bug) which can be a bit disconcerting to the new user.

What happened was that when you used the mouse to scroll a window,
either the main scroll bars or the up and down arrow icons, the cursor
didn't move as the window scrolled. For example, if you loaded a long
file and used the mouse and scroll bars to move part way through it all
appeared to work normally. However if you pressed the Down Arrow key to
scroll down just one more line something very unexpected happened. You
suddenly discovered that were are back at the start of the file with the
cursor on the second line!

This was completely different from the way that Edit and most other text
editors work. With these the cursor always remains within the window.
With later (>1.10) version the cursor can also be confined in this way
and the example !Config file supplied actually does this.

Some users have now become accustomed to the 'old' method, myself
included, and have discovered that it does have it's uses. If you want
to 'browse' through the file you are editing then you can do so using
the scroll bars, but to return quickly to your original position (the
position of the cursor) all you need to do is tap one of the 'arrow'
keys and Zap will take you back there. This is another example of how
useful it is to be able to customise Zap, you aren't constrained by what
the Author decides is best but can change it to suit yourself.



    Configuring Zap
    ===============
Zap uses two files for configuration. These are found in the !Zap
application directory. One is a Data file called !Config. This will not
be present when you first get your copy of Zap, it is created when you
select 'Save Options' from the 'Options' sub-menu. It sets colours, wrap
widths, cursor type, and most of the other 'visual' layout parameters.

The most important is a text file called 'Keys'. This contains the
things that define how Zap will operate, including the all important key
binding table which tells Zap which keys should perform which functions.

With this instruction file you should find two files which are intended
to replace the standard configurations. There should also be a Drawfile
of a keystrip. This 'keys' file is designed to mimic Edit to enable you
to become accustomed to Zap as easily as possible. Many of the more
powerful functions of Zap cannot be directly accessed via keystrokes
because they don't have keys assigned with this file. As you become more
experienced with Zap you will wish to alter the keys file so you can
access these functions but for the present they would only be confusing.
The full list of functions which can be bound to keys can be found in
the file 'Commands' in the 'Docs' sub-directory of the !Zap application
directory. This also contains instructions for creating your Keys file
and with the aid of this, the original Keys file supplied with Zap and a
bit of experimentation you should be able to work out how to make Zap
operate in the way that you require.

To use these configuration files first make a working copy of Zap. If
you have a hard disc then copy zap onto your hard disc, if you are using
floppies then copy it to a new disc. Now delete the 'keys' file from the
application directory of this working copy and replace it with the file
of the same name supplied with this file. You should also copy the
!Config file into the application directory.

When you start up this version of Zap it will use the keys shown on the
next page which are roughly equivalent to Edit. There are a few extra
ones which have no direct equivalent but are so useful that I didn't
want to leave them out. These are not the keys that I normally use and
no doubt you won't use them for long before you begin to make changes.

As yet Zap has no equivalent to Edit's the 'change LF<->CR' functions.
LF<->CR can be mimicked by 'search and replace'. For example, to change
all CR's to LF's enter in the 'Search' icon -

    \13

and in the 'replace' icon -

    \10

or to delete al CR's from a LF-CR terminated text file from a PC in the
search icon -

    \13

and leave the 'replace' icon blank.



    F1          Execute 'learnt' key sequence (no equivalent)
    F3          Save
    F4          Find and Replace
    F5          Goto line or address
    F6          Mark beginning or end of block
    F7          Copy marked block to cursor
    F8          Renumber (BASIC mode only)
    F9          Redo last action
    F10         Undo last action

    Sh-F1       Toggle Insert/Overtype modes
    Sh-F3       Immediate Save (no dialogue box)
    Sh-F4       Find (no equivalent)
    Sh-F6       Clear marked block
    Sh-F7       Move marked block to cursor
    Sh-F8       Delete marked block

    Ctrl-F2     Close current window
    Ctrl-F5     Toggle wordwrap on/off
    Ctrl-F6     Format paragraph

    Ctrl-B      Split line at cursor position (for BASIC mode, B=Break)
    Ctrl-C      Copy marked block to cursor
    Ctrl-L      Learn key sequence (no equivalent)
    Ctrl-J      Join two lines (for BASIC mode)
    Ctrl-N      Next match when Searching (no equivalent)
    Ctrl-P      Previous match when Searching (no equivalent)
    Ctrl-S      Swap case of character at cursor (no equivalent)
    Ctrl-V      Move marked block to cursor
    Ctrl-W      Next window. If there is more than one window open this
                will move the cursor to the next one (no equivalent)
    Ctrl-X      Delete marked block
    Ctrl-Z      Clear marked block

    Delete      Delete backwards
    Copy        Delete forwards
    Ctrl-Copy   Delete entire line
    Sh-Copy     Delete from cursor to end of line (no equivalent)
    Sh-Delete   Delete from cursor to start of line (no equivalent)
    Print       Print file (no equivalent)

    Sh-Ctrl F0 to F7  Change to Zap mode 0-7 (more about these next)





    Zap Modes
    =========
Unlike Edit Zap has a series of different 'modes'. The mode you will
probably use most, and the one that is similar to Edit, is Text Mode.
The reason for the different modes is to enable you to edit data in a
variety of ways. When you load a file into Zap it decides which is the
most appropriate mode to use, although like most features this can also
be defined in the keys file. Each mode can have various options, such as
the wrap width, set by the user.

For the present I shall concentrate Text (mode 0) and BASTXT (mode 6)
because these are almost directly equivalent to the way that Edit works,
and BASIC (mode 5) because you may prefer this to BASTXT for editing
Basic programs. However you may wish to experiment with others. The two
others you will probably find most useful are Byte (mode 1) and Code
(mode 4).

Byte mode edits a file in a window that looks like a disc sector editor.
It is particularly useful for editing Data files or other files which
don't contain normal text.

Code mode shows a machine code or compiled program in in disassembled
format. In fact it makes Zap into a simple disassembler. There are
various functions which can be used when in this mode, such as following
Branches, assembling instructions, etc.

BASTXT mode is the mode that most people prefer for editing Basic
programs. This converts a tokenised program to text when it is loaded
and back to Basic when you save it. It enables all the 'normal' editing
functions to be used just as if you were working on a text file. This is
the way that the RiscOS 3 version of Edit handles Basic programs and for
this reason I have used it as the default for this primer.

If you think that Acorns Basic Editor is wonderful (!) then you may
prefer to use BASIC mode (mode 5). This operates in a similar manner to
Acorns (now obsolete) Basic Editor. If you want to use Zap in BASIC mode
(see below) then you will need to use the 'split line' and 'join line'
keys, otherwise these can be ignored.

In the past I regarded the 'standard' Basic mode as so inferior to
BASTXT mode that I advised people not to use it. This is because when
Zap is in BASIC (as compared with BASTXT) mode it previously operated as
a Line Editor. This meant that only complete lines could be copied or
moved, you had to worry about things like renumbering, using a special
key to split or join a line etc. Basic mode can now be set so, although
the program is edited in tokenised form, doesn't have these disadvantage.
Previously the only advantage with BASIC mode was that it could handle
GOTO's properly and automatically (but then you wouldn't put a GOTO
anywhere in your programs, would you?).


However from version 1.1 Zap has a feature which makes BASIC mode more
attractive. It can display the constituent parts of a program in
different colours. Keywords, line numbers, REM's and string constants
can all have their own colours defined which makes it much easier to
'read' a program and see how it is made up. Inexperienced programmers
often find this invaluable. Personally I still prefer the superior
editing ability of BASTXT mode but try them both and choose the one that
you like best.

To change the mode that Zap uses by default load Zap and go to the
sub-menu 'Options' on the main menu. Click on 'Edit Keys'. This makes
Zap load the current Keys file from it's own application directory ready
for you to edit it. Press F5 to bring up the 'Goto' window, enter line
number 200 and press RETURN. Zap will now display the lines in this
region and you will find that about here are defined the modes that Zap
uses for each type of file. You should see a line -

    Basic          &1FFB    BASTXT

Change this to

    Basic          &1FFB    BASIC

Press SHIFT-F3 to 'quicksave' the Keys file (ie. it will be Saved
without any further prompting) and close the file window. Now click on
'Reload Keys' from the Options sub menu and Zap will re-interpret the
Keys file so the next time you load a basic program it will be in BASIC
mode instead of BASTXT. If you find you prefer the alternative method
just change the Keys file back again.



    Setting the Options
    ===================
Each Zap mode can have many options set independently of the general
options, other items are common to all modes. I shall describe briefly
how you make these changes and then let you experiment for yourself.

The 'Options' sub menu is where most of this customising is carried out.
As this leads to a series of sub-menu's you will probably find it best
to open this menu and drag it to the left of the screen because
otherwise as you open the other sub-menus they will obscure each other.
Keep the mouse pointer within the menus as you do this otherwise they'll
all close and you'll have to start again.

I shall concentrate on only two items, Colours and Width. The first
thing you need to understand (or you'll soon become very confused) is
that when you change an option like Width it changes ONLY for the mode
that is currently selected.

Go to the Options-> Mode sub menu and click on 'Text'. (Click on it with
ADJUST otherwise all the menus will close and you'll have to start
again. Now open the Options-> Display-> Width sub menu and look at the
width shown. If you are using the !Config file supplied with this text
it will be 112. Now go back to Config-> Mode and click on 'BASIC'. Look
at the Width after this and you will see it has changed to 76. What this
shows is that Zap has a different Width for each mode, and so if you
want to change it the change you make will apply ONLY to the currently
selected mode.

Precisely the same situation applies to colours. The only difference
here is that to avoid having to change every colour in every mode you
can select 'All' on the Options-> Display-> Colours menu and the
colour(s) you select will be made in every mode. If you want one mode to
have different colours from another then de-select 'All' and select that
mode and the colours will apply to that mode only.

There is a slight departure from this when you select BASIC mode. You
will find three more items appear on the Options-> Display-> Colours
menu. These set the colours used for REM's, Basic keywords and string
constants. Obviously these only apply in BASIC mode which is why they
don't appear if any other mode is selected.

When you are satisfied with your choices click on 'Save Options' on the
Options menu.

You will probably spend a bit of time exploring the various options and
discovering the effects of the changes. Most are fairly self evident and
the more obscure ones probably will not concern you at this stage.



    Using Search and Replace
    ========================
Unlike Edit, Zap has two Search windows. One simply 'finds' what you are
looking for, the other enables you to replace it with something else.
The advantage of this over Edits single window is that if you just want
to find something you can't accidentally press the wrong key and replace
it with a 'null string' (ie. delete it).

The way that Zap's search function works is completely different from
Edit and it will probably take you a while to get used to it. However it
is MUCH more powerful and flexible.

You have a choice of where you want the search to start from. You can
begin from the cursor position or from the start of the file. You also
have a choice of whether you want the search to be forwards or
backwards. From version 1.2 you can even search ALL the files curently
'active', not just the present 'window'. Another feature is that you can
choose the 'output' for the search. This enables you to do more than
just 'find' something. If you select 'Cursor' then the cursor will
simply move to wherever the search string is found, just like Edit. If
you choose 'To buffer' then when Zap finds a match it will create a new
file and copy each line where a match is found to this new file. A
window will open containing a list of all the lines containing a match
and you can save or edit this as usual. If you want to go in your
original file to any of the matches displayed in the new window then
just 'click' on the line in this window and Zap will move the cursor to
that line in your original file. Alternatively just use the 'go to line'
function since each match will have it's 'line number' shown.

Like Edit certain special characters can be used. These are all defined
by being preceded by the '\' character. A full list of these can be
found in the !Help file but a few examples are shown.

    \10         Matches ascii character number 10, eg the normal
                end-of-line character. \12 would find character 12 etc.
    \|          Matches one string OR another. For example John\|Fred
                would match John or Fred.
    \A          CTRL-A, \B would be CTRL-B etc.
    \#          Any character
    \*          Any number of the previous string. eg A\* would match A,
                AA, AAA etc.
    \<          Finds the string only at the start of a line. eg. \<fred
                only finds 'fred' if it's the first word on a line.

The biggest change from the way that Edit's Search function operates is
that Zap can use Search Macro's. If you click on 'Show Macros' in either
Search window the Macro Window will open. This shows the current macros.
When you enter a Search string if any of the characters you enter has a
macro defined for it then that macro will be substituted during the
search. I am not going into great detail about these. You will need to
experiment to find out exactly how they work and which macros you wish
to use. Like most other things they are all defined in the Keys file and
you will be able to see the current ones near the end.



    Undo and Redo
    =============
These are functions which have no direct equivalent in !Edit but which
are found in most 'proper' editors and are extremely useful.

'Undo' does exactly what it's name suggests - it reverses the effects of
the last action taken. For example, if you had just deleted a line and
then realised that you had deleted the wrong line, or for for some other
reason wish that you hadn't done so, then pressing the UNDO key (F10
with the simple keymap supplied with this file) will reverse the action
and restore the line. Undo can't put right every error you might make,
but it can restore most 'mistakes' and save you a lot of trouble.

Redo (F9) isn't quite so simple to understand. Basically it undoes the
last Undo action. This can get quite complicated so I will give a simple
example and then you can play around with it for yourself.

With the cursor at the start of the line type -

        123456789

Now press DELETE twice to delete the '8' and '9' so you have -

        1234567

Now press F10 (Undo) twice and the '8' and '9' will be restored.

To see the effect of Redo press F9 twice and the '8' and '9' will vanish
again as you 'undo' the action performed by the Undo key.



    Learn
    =====
This is another very powerful function which exists in all 'proper'
programmers editors but not in Edit. The idea is that Zap can 'learn' a
series of keystrokes and play them back on command. When editing or
modifying a file you may need to carry out the same operation many
times. Instead of being forced to manually repeat it you can teach Zap
what you want it to do and save yourself all the repetitive work.

For example, if you had a text file which consisted of a a series of
lines made up of a code number, a name, and a description, like this;

189554       Screw, Widget         The screw that fits the Widget
295677       Bolt, Mangel          The bolt that attaches the Mangel

Now assume that you want to reduce the gaps between the three items so
that you can add to the descriptions like this;

189554   Screw, Widget    The screw that fits the Widget
295677   Bolt, Mangel     The bolt that attaches the Mangel

This is the same thing but with four spaces deleted between each section
which let's you add eight characters to your description with the same
line length. The way this is done 'manually' is to place the cursor
after the number and press COPY four times (or whatever key you have
chosen as Delete Forward), move it just after the first section and
press it four times again, then move down to the next line and repeat,
etc, etc. Instead of doing all this you can use Learn to do it for you.

Move the cursor to the start of the first line. Press Ctrl-L to tell Zap
to start learning your keystrokes. Press the Right Arrow key six times.
This will move the cursor just after the number. Each time you press the
key the computer will 'beep' to remind you that Zap is recording what
you do. Now press the Copy key four times to delete the four spaces,
press Right Arrow eighteen times to move to the second 'gap' and Copy
four times once again. Now press Ctrl-Left Arrow to move to the start of
the line and Down Arrow to move down one line. When you have done this
the cursor should be at the start of the next line (ready to carry out
the next operation) and the line should be 'closed up' like the second
example. As you have finished the 'learning' process press Ctrl-L again
to tell Zap to stop recording what you do.

All you need to do now is press F1 which makes Zap Execute the learnt
keystrokes and by 'playing back' the learnt sequence Zap will carry out
exactly the same operation on the second line that you did manually on
the first. You will then find that the cursor has been moved to the
third line, just as you moved it to the second, so just press F1 again
to do the third line and so on to the end of the file.

Of course it might have been simpler in this case to use 'Search and
Replace' but this does show how the Learn function can can save a lot of
typing and, because each sequence will be carried out precisely as the
first, there is less chance of mistakes.